Add html repr #883

edeno · 2023-06-28T02:25:51Z

Motivation

Inspired by the handy html reprs provided by dask, xarray, and pandas (see this blog post for some examples), I wanted to create an easy visual representation of the pynwb file that allows users to:

Easily navigate the structure of the nwb file.
Display how to navigate to nwb objects via tooltip (e.g. nwb_file.fields["processing"]["behavior"].fields["data_interfaces"][ "finger_pos" ].fields["starting_time"])
Allow the user to easily copy this code.

This visualization only displays when using a jupyter notebook, but I believe enough users use these tools for it to be of use. While this does overlap with some of the functionality of NWB Widgets, it is lighter-weight, requires no additional installation, and does no plotting. The goal is for the user to figure out what is in the contents of the nwb file and access the data quickly.

The code below should show off the functionality for an arbitrary NWB file, although the copying of the tooltip is still a work in progress.

How to test the behavior?

import pynwb


class NWBDisplay:
    CSS_STYLE = """
    <style>
        .nwb-fields { font-family: "Segoe UI", Roboto, sans-serif; }
        .nwb-fields .field-key { font-weight: bold; }
        .nwb-fields .field-value { color: #00788E; }
        .nwb-fields details > summary { cursor: pointer; }
        .nwb-fields details > summary:hover { color: #0A6EAA; }
    </style>
    """

    JS_SCRIPT = """
    <script>
        function copyToClipboard(text) {
            navigator.clipboard.writeText(text).then(function() {
                console.log('Copied to clipboard: ' + text);
            }, function(err) {
                console.error('Could not copy text: ', err);
            });
        }
        
        document.addEventListener('DOMContentLoaded', function() {
            let fieldKeys = document.querySelectorAll('.nwb-fields .field-key');
            fieldKeys.forEach(function(fieldKey) {
                fieldKey.addEventListener('click', function() {
                    let accessCode = fieldKey.getAttribute('title').replace('Access code: ', '');
                    copyToClipboard(accessCode);
                });
            });
        });
    </script>
    """

    def __init__(self, nwb_obj):
        self.nwb_obj = nwb_obj
        self.fields = nwb_obj.fields

    def _repr_html_(self):
        html_repr = self.CSS_STYLE
        html_repr += self.JS_SCRIPT
        html_repr += "<div class='nwb-wrap'>"
        html_repr += (
            "<div class='nwb-header'><div class='xr-obj-type'>NWB File</div></div>"
        )
        html_repr += self.generate_html_repr(self.fields)
        html_repr += "</div>"
        return html_repr

    def generate_html_repr(self, fields, level=0, access_code=".fields"):
        html_repr = ""

        if isinstance(fields, dict):
            for key, value in fields.items():
                current_access_code = f"{access_code}['{key}']"
                if (
                    isinstance(value, dict)
                    or isinstance(value, list)
                    or hasattr(value, "fields")
                ):
                    html_repr += f'<details><summary style="margin-left: {level * 20}px;" class="nwb-fields field-key" title="{current_access_code}">{key}</summary>'
                    if hasattr(value, "fields"):
                        value = value.fields
                        current_access_code = current_access_code + ".fields"
                    html_repr += self.generate_html_repr(
                        value, level + 1, current_access_code
                    )
                    html_repr += "</details>"
                else:
                    html_repr += f'<div style="margin-left: {level * 20}px;" class="nwb-fields"><span class="field-key" title="{current_access_code}">{key}:</span> <span class="field-value">{value}</span></div>'
        elif isinstance(fields, list):
            for index, item in enumerate(fields):
                current_access_code = f"{access_code}[{index}]"
                html_repr += f'<div style="margin-left: {level * 20}px;" class="nwb-fields"><span class="field-value" title="{current_access_code}">{str(item)}</span></div>'
        else:
            pass

        return html_repr


nwb_file = pynwb.NWBHDF5IO(
    "test.nwb", mode="r"
).read()

NWBDisplay(nwb_file)

Example display

bendichter · 2023-06-28T03:23:07Z

woah, awesome! Let's make this the default output for containers! @edeno what happens when you add this as a method of Container:

hdmf/src/hdmf/container.py

Line 383 in 2f9ec56

class Container(AbstractContainer):

edeno · 2023-06-28T03:35:48Z

I believe the commit I added in the pull request did this and should be inherited. Not quite sure how to test this though.

bendichter · 2023-06-28T03:41:31Z

ah, ok. I'll take a look

bendichter · 2023-06-28T03:52:27Z

@edeno

I got it to work! I fixed two typos and modified the styles bit. Now this is displayed by default in Jupyter:

codecov · 2023-06-28T03:53:01Z

Codecov Report

Patch coverage: 80.00% and project coverage change: -0.04 ⚠️

Comparison is base (2f9ec56) 88.20% compared to head (0043287) 88.17%.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #883      +/-   ##
==========================================
- Coverage   88.20%   88.17%   -0.04%     
==========================================
  Files          44       44              
  Lines        9032     9067      +35     
  Branches     2587     2595       +8     
==========================================
+ Hits         7967     7995      +28     
- Misses        752      757       +5     
- Partials      313      315       +2

Impacted Files	Coverage Δ
src/hdmf/container.py	`90.62% <80.00%> (-0.51%)`	⬇️

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

bendichter · 2023-06-28T03:53:17Z

The triangles aren't showing up for me, but I still think this looks pretty good

edeno · 2023-06-28T04:41:34Z

Hm, I do think the triangles are quite useful to indicate you can "open a level". Are you still able to go down levels without the triangles?

bendichter · 2023-06-28T04:54:41Z

Yes, and I changed the styles so the bold indicates expandable. I like the triangles too. I'm not sure why they aren't showing up for me. I'm not an HTML/CSS expert but I'd be happy to run anything you want to try.

I'm using Chrome in a Jupyter notebook on a mac.

oruebel · 2023-06-28T05:55:23Z

I'm not sure why they aren't showing up for me.

My guess is that the font you are using is not supported so the browser falls back on a different font. I.e., I suspect the issue is with .nwb-fields { font-family: "Segoe UI", Roboto, sans-serif; }. Segoe UI is I believe a Windows font so it probably doesn't come with Chrome or Firefox. A quick google search suggests Open Sans could potentially be an alternative, but I'm not sure if that font has the triangle symbol.

woah, awesome!

I agree, that's pretty cool.

what happens when you add this as a method of Container:

I think we probably also would want to add a _repr_html_ for class Data or if the representations are the same for both Data and Container then this could be moved to AbstractContainer instead.

bendichter · 2023-06-28T16:04:19Z

I'm still not getting triangles even with the new font

bendichter · 2023-06-28T16:04:49Z

bendichter · 2023-06-28T16:27:21Z

I few other minor points:

Currently, the name "NWB File" is hard-coded as the title. I'd like to change this so that any neurodata object can be viewed this way. For example, here is visualization on a lone ElectricalSeries object.

This is almost good, but we should dynamically set the text of the title based on the name of the object. I have changed it to the following rule:

if self.__class__.__name__ == "NWBFile":
    nwb_header_text = "NWBFile"
elif self.name == self.__class__.__name__:
    nwb_header_text = self.name
else:
    nwb_header_text = f"{self.name} ({self.__class__.__name__})"

Currently, the values of datasets are printed. This isn't a big problem in most cases. Usually, large datasets are np.ndarray objects that have a reasonable printing strategy, as seen above. If being read from disk, datasets are h5py or zarr arrays, both of which have reasonable printing strategies.

However, there is currently an edge-case when you have large datasets stored in Python native list objects. In this case, the current print function prints every value:

This won't be an issue for any dataset that has been written and read back from disk, so I don't think it's a huge issue, but just something to be aware of

oruebel · 2023-06-28T16:35:34Z

src/hdmf/container.py

+        if self.__class__.__name__ == "NWBFile":
+            nwb_header_text = "NWBFile"


Can you clarify why this first part of this if statement to check for "NWBFile" as a name is necessary? Isn't this covered by the second part? Also, it seems strange to check for NWBFile in HDMF.

It's not covered by the second part because the root NWBFile object technically has the name "root".

Another option is to take this clause out let the name title of an NWBFile object be: "root (NWBFile)".

I suppose another option could be to create a method for this and override it in the NWBFile class.

let the name title of an NWBFile object be: "root (NWBFile)"

I think that would be fine. We can always customize in PyNWB if necessary. Alternatively you could also check for:

if self.name == 'root'`: nwb_header_text = self.__class__.__name__

but to be honest, I would go with consistency here and just let be root (NWBFile)

oruebel · 2023-06-28T17:49:57Z

A more nit-picky comment. I would suggest to remove the nwb prefix from variable names.

edeno · 2023-06-28T19:07:00Z

With respect to the triangle, it should just be rendered via the html tag details (reference here), so it shouldn't be anything fancy. For me it works in jupyter lab in both Chrome and Firefox.
@bendichter Does the details tag display the triangle here on the github PR?

Test

bendichter · 2023-06-28T19:08:13Z

Yes, it has always worked within GitHub. There must be some strange styling going on in my jupyter notebook

edeno · 2023-06-28T19:24:56Z

Based on this stack overflow, @bendichter can you try the following CSS:

        CSS_STYLE = """
        <style>
            .container-fields {
                font-family: "Open Sans", Arial, sans-serif;
            }
            .container-fields .field-value {
                color: #00788E;
            }
            .container-fields details > summary {
                cursor: pointer;
                display: list-item;
            }
            .container-fields details > summary:hover {
                color: #0A6EAA;
            }
        </style>
        """

bendichter · 2023-06-28T19:30:30Z

unfortunately that did not do the trick.

bendichter · 2023-06-29T00:29:54Z

@edeno and @oruebel adding the styling in like this worked for me!

bendichter · 2023-06-29T00:44:28Z

What do you guys think of hiding np arrays behind a details like this?

oruebel · 2023-06-29T03:09:42Z

What do you guys think of hiding np arrays behind a details like this?

That looks good to me. Looks like all this needs is a unit test and it is good to go

bendichter · 2023-06-29T16:21:08Z

I think this is a good checkpoint. It provides clear value above what we have before and works reasonably well. I also think there are lots of opportunities for improvements, e.g.

nice tablular rendering for DynamicTables
using tooltips for the doc string of each attribute
smarter handling of datasets

The nice thing about this implementation is that downstream classes can implement their own custom html

bendichter · 2023-06-29T16:21:52Z

@oruebel what are you envisioning for a test for this feature?

bendichter · 2023-06-29T16:48:25Z

@oruebel I added the very basic:

def test_repr_html_(self):
    assert isinstance(Container('obj1')._repr_html_(), str)

which ensures that ._repr_html_() runs without error, but does not check for string equivalence.

oruebel · 2023-06-29T17:31:15Z

what are you envisioning for a test for this feature?

I think having a test that checks string equivalence for a Container that covers more of the different cases in the function would be great.

oruebel · 2023-06-29T23:19:04Z

Looks good to me. Thanks for this great new feature.

rly · 2023-06-29T23:32:55Z

Thanks @edeno for the enhancement!

Add html repr

2fd1d84

fix references to _generate_html_repr and adjust styles a bit

09a1dba

edeno added 2 commits June 27, 2023 22:59

Update font to be more cross-browser compatible

6431fd9

Fix formatting

02935e1

oruebel added topic: docs Issues related to documentation category: proposal proposed enhancements or new features priority: medium non-critical problem and/or affecting only a small set of users topic: PyNWB Issues related to the use HDMF in PyNWB labels Jun 28, 2023

oruebel added this to the Next Release milestone Jun 28, 2023

header reflects class name

78b7819

oruebel reviewed Jun 28, 2023

View reviewed changes

rmv all mention of NWB

06b874d

Ensure summary display is a list item.

c6cf06d

bendichter added 2 commits June 28, 2023 20:29

adding list-item display styling

9dd8518

Merge remote-tracking branch 'edeno/dev' into edeno_dev

6c44193

display numpy arrays

edb1ccc

add bare-bones test

8775016

add unit test which includes child container, dataset, and string

0043287

bendichter requested a review from oruebel June 29, 2023 20:23

oruebel approved these changes Jun 29, 2023

View reviewed changes

bendichter merged commit 6043e77 into hdmf-dev:dev Jun 29, 2023
28 checks passed

oruebel mentioned this pull request Jun 30, 2023

TermSet Integration with up-to-date HDMF #880

Merged

15 tasks

rly mentioned this pull request Jul 6, 2023

[Feature]: Enhance TermSet #893

Open

3 tasks

bendichter mentioned this pull request Jul 8, 2023

better NWB file exploration flatironinstitute/neurosift#14

Closed

rly removed this from the 3.14.0 milestone Apr 11, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add html repr #883

Add html repr #883

edeno commented Jun 28, 2023 •

edited

Loading

bendichter commented Jun 28, 2023 •

edited

Loading

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

bendichter commented Jun 28, 2023

codecov bot commented Jun 28, 2023 •

edited

Loading

bendichter commented Jun 28, 2023

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

oruebel commented Jun 28, 2023 •

edited

Loading

bendichter commented Jun 28, 2023

bendichter commented Jun 28, 2023

bendichter commented Jun 28, 2023 •

edited

Loading

oruebel Jun 28, 2023

bendichter Jun 28, 2023 •

edited

Loading

oruebel Jun 28, 2023

oruebel commented Jun 28, 2023

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

bendichter commented Jun 29, 2023

bendichter commented Jun 29, 2023

oruebel commented Jun 29, 2023

bendichter commented Jun 29, 2023

bendichter commented Jun 29, 2023

bendichter commented Jun 29, 2023

oruebel commented Jun 29, 2023

oruebel commented Jun 29, 2023

rly commented Jun 29, 2023

		if self.__class__.__name__ == "NWBFile":
		nwb_header_text = "NWBFile"

Add html repr #883

Add html repr #883

Conversation

edeno commented Jun 28, 2023 • edited Loading

Motivation

How to test the behavior?

Example display

bendichter commented Jun 28, 2023 • edited Loading

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

bendichter commented Jun 28, 2023

codecov bot commented Jun 28, 2023 • edited Loading

Codecov Report

bendichter commented Jun 28, 2023

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

oruebel commented Jun 28, 2023 • edited Loading

bendichter commented Jun 28, 2023

bendichter commented Jun 28, 2023

bendichter commented Jun 28, 2023 • edited Loading

oruebel Jun 28, 2023

Choose a reason for hiding this comment

bendichter Jun 28, 2023 • edited Loading

Choose a reason for hiding this comment

oruebel Jun 28, 2023

Choose a reason for hiding this comment

oruebel commented Jun 28, 2023

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

edeno commented Jun 28, 2023

bendichter commented Jun 28, 2023

bendichter commented Jun 29, 2023

bendichter commented Jun 29, 2023

oruebel commented Jun 29, 2023

bendichter commented Jun 29, 2023

bendichter commented Jun 29, 2023

bendichter commented Jun 29, 2023

oruebel commented Jun 29, 2023

oruebel commented Jun 29, 2023

rly commented Jun 29, 2023

edeno commented Jun 28, 2023 •

edited

Loading

bendichter commented Jun 28, 2023 •

edited

Loading

codecov bot commented Jun 28, 2023 •

edited

Loading

oruebel commented Jun 28, 2023 •

edited

Loading

bendichter commented Jun 28, 2023 •

edited

Loading

bendichter Jun 28, 2023 •

edited

Loading